Alessandro Levi Montalcini
C.so Re Umberto 10
10121 Torino
Italy
e-mail: lmontalcini@pmn.it

KeyQuencer 1.01 documentation - June 1994

• Shareware - $10 - cash only
◊  This control panel is distributed as shareware: if you like it please honor the shareware system by sending $10 to the author at the address above. Since cashing international cheques is very expensive, please send cash only (U.S. dollars are best, but any European currency is fine). Use the “Save Registration Form…” button below to generate a text file with all the data I need, then print it with TeachText or with your word processor (don’t worry about formatting the text). If you don’t like printed stuff just write down a note with your name, your address and the name and version of the program you’re registering.
◊  If you work on the Macintosh, there are many things you can send me instead of the money. Here are some suggestions: original software (but don’t send any shareware/freeware unless you’re the author), books or computer-related magazines (any free issue or subscription will be welcome), CD-ROMs, any piece of new or used hardware, or anything else you’ve created.
◊  There’s still another thing you could do: I’ll finish my physics studies sometime in 1996 and I’m looking for a one-year job as a programmer (or maybe a scientist?) outside of Italy. Let me know if you have anything to offer.
◊  If you can’t afford any of the above an e-mail, a postcard or a letter will be welcome. I speak English, French and Italian. Please forgive me if I don’t answer to all of your letters - I am often overloaded with my school work.

• Special offers
◊  The following people may register KeyQuencer at a special price ($5 instead of $10):
  - all registered users of any of my other shareware programs (that is, anyone who already sent me something);
  - all high-school and college students;
  - anyone else who is under 25.

• Introduction
◊  KeyQuencer is a very useful control panel that lets you perform complex tasks with one keystroke. I wrote it because I wasn’t satisfied with the commercial macro engines currently available, as they require lots and lots of memory and often fill it with less than useful stuff. KeyQuencer uses a scripting approach; it can’t watch your steps to learn new sequences as other commercial packages do. This requires a bit more work when you define a new sequence, but the final impact of KeyQuencer on your system is a lot smaller in terms of memory usage and processor time.
◊  KeyQuencer works with special structures called macros, which are defined by a name, a key combination and a text. The macro name only appears in the control panel; it allows you to pick the right macro for editing or deletion and to have an easily readable list of all your macros. The macro key is the key combination you use to activate the macro: when KeyQuencer detects a macro key, it starts executing the macro without stopping the applications you’re using. The actual task performed by the macro is defined by the macro text, which is a sequence of simple instructions. KeyQuencer has no built-in instructions; all the instructions are kept in separate external files called extensions. This allows you to leave unused extensions out of your Mac’s memory and to add more extensions as they become available.

• Installation
◊  System 7: Move the KeyQuencer control panel into your Control Panels folder (inside the System folder). Move the KeyQuencer Extensions folder into any one of the Preferences, Extensions, Control Panels or System folders. Move the KQ Apple Events extension into the Extensions folder if you plan to use the "Open" or "Quit" commands. Restart your Macintosh, then open the Control Panels folder and double click on KeyQuencer’s icon to configure it.
◊  System 6: Move the KeyQuencer control panel and the KeyQuencer Extensions folder inside your System folder. Restart your Macintosh, then open the Control Panel desk accessory to configure it. The KQ Apple Events extension doesn’t work with system 6, so you won’t be able to use the "Open" and "Quit" commands.
◊  Japanese and other non-roman systems: Don’t forget to enable the WorldScript II work-around in the Preferences dialog (the work-around is installed at next restart).

• The control panel
◊  The KeyQuencer control panel allows you to view and edit macros and to assign them a keystroke. The following commands are available in the control panel’s fake menu bar:
◊  New Macro: Creates a new macro and brings up the macro editor window.
◊  Edit Macro: Brings up the macro editor for the first selected macro (the first one that is highlighted in the macro list). Does nothing if no macro is selected.
◊  Delete Macro(s): Deletes all selected macros after asking if it’s OK to do so. This operation cannot be undone, whereas cutting the macros via the Edit menu leaves them in the clipboard. Does nothing if no macro is selected.
◊  Preferences…: Displays the preferences dialog. You may choose whether to display the key combinations in the list or not; when visible, the key combinations may be displayed graphically, as right-aligned text or just appended to the macro name. The activity monitor is a red square that gets drawn in the menu bar when a macro is running; you can turn it off if it bugs you. You may also turn the startup icon on and off. The last two options deal with special workarounds I made for Microsoft Word’s nonstandard implementation of the Macintosh event loop and for Apple’s own WorldScript II. KeyQuencer doesn’t work in Word if the first workaround is disabled, while the second is useful when working with non-roman script systems such as Japanese.
◊  Import Macros…: Imports all the macros contained in a previously exported macro file or in another KeyQuencer control panel. If duplicate names are found for some macros, you’ll be asked whether you want to skip them.
◊  Export Selected…: Exports the currently selected macros to an external macro file, so you can save them for later use or for distribution. Does nothing if no macro is selected.
◊  Edit Menu: All the Edit menu commands work as expected.
◊  About KeyQuencer…: Displays this text and lets you save it as a text file. You may also save a text file with your personal registration form.
◊  Save Registration Form…: Asks you to enter you name and address and saves a text file with your personal registration form, which can be printed with TeachText or any other text editor.
◊  Keyboard Shortcuts…:  Displays all control panel shortcuts. KeyQuencer can’t assign command keys to its menu commands because it is not an application, so the shortcuts are implemented through the shift key.
◊  Memory Usage…: This tells you exactly how much of your Mac’s memory is being used by KeyQuencer. A full working setup with all the extensions installed and lots of macros typically needs about 64K. The KQ Apple Events extension, which is a background-only application designed to support the "Open" and "Quit" extensions, takes another 30K if it’s installed.
◊  The macro list displays all currently defined macros in alphabetical order. You may double click on a macro to edit it (same as the Edit Macro command). Holding down the shift or command key when clicking in the list lets you select more than one macro at a time; multiple selections are useful for the Export and Delete commands described above.
◊  The on/off master switch enables or disables KeyQuencer.

• Stopping a macro
◊  KeyQuencer provides a special keystroke - Cmd-Shift-Return - that stops any running macro and flushes the macro queue. This keystroke may not be changed or assigned to any other macro.

• Shortcuts
◊  Typing some characters when the control panel is open selects the first macro in the list whose name matches the characters typed. You should not use the shift key while typing because it is used as a command key replacement for KeyQuencer’s menus. 
◊  Some keys may be used as shortcuts when KeyQuencer’s control panel is the front window. Some have to be typed alone, others need the shift key; I could not use the command key because the Finder doesn’t let control panels use it.
  - shift-N = New macro
  - shift-E = Edit macro
  - shift-D or backspace = Delete macro(s)
  - shift-I = Import macros
  - shift-X = eXport macros
  - shift-P = Preferences
  - shift-A = select All
  - shift-S, return or enter = Select none
  - down arrow, right arrow or tab key = select next macro
  - up arrow, left arrow or shift-tab = select previous macro

• Cut and paste
◊  The standard Edit menu commands work fine in KeyQuencer’s control panel. You may use the Scrapbook desk accessory to store your macros for later use (you'll be able to see the macro names there). Exporting to an external file is more convenient if you want to move your macros from one Mac to another.

• Known limitations and future improvements
◊  All key assignments are global; there is no way to let a keystroke “flow” through a macro once it’s been intercepted by KeyQuencer. This means you shouldn’t assign any keystroke that is meaningful to your applications, since you wouldn’t be able to have it act as usual when needed. This is unlikely to change in future versions because of the way KeyQuencer works; I had to write it this way to keep it as clean and compatible as I could. The only advantage is that you can’t mess up by calling the wrong macro when you switch from one application to another. If many of you really miss this feature then I’ll try to think about it.
◊  There are a couple of things that just didn’t make it into this first release. These limitations will eventually be addressed in future versions, especially if many (registered) users complain about them.
  - Macros defined in the control panel can’t have more than 255 characters (you can send longer macros from HyperCard and AppleScript, this limitation only affects the control panel macro editor). Worse yet, the control panel doesn’t inform you when your macro is too long - it just chops it. This will definitely be fixed.
  - There is no way to call a macro from a menu, or to display a quick reference of all the key assignments; you have to open the control panel when you forget your keys (here’s a cool macro to do it: SwitchApp "Finder", then Open "Your HD:System Folder:Control Panels:KeyQuencer").
  - There is no PopUpMenu extension yet (I didn’t have the time to write one, but I’ll fix that as soon as possible).
  - The menu bar activity monitor is ugly (even though it’s very compatible). I’ll try to transmogrify it into a cool small icon if you really can’t stand the good ol’ red square.
  - The control panel doesn’t have a separate preferences file, so you have to manually export your macros if you don’t want to lose them when you trash the control panel itself (be careful - this will surely happen when you upgrade to a newer version).
◊  KeyQuencer doesn’t have a timer, but it would be easy to add one through a dedicated application. You could leave such an application in your “Startup Items” folder and have it execute KeyQuencer macros at specific times. I don’t need a timer myself, so let me know if you do.
◊  Desk accessories intercept keystrokes before KeyQuencer; this isn’t usually a problem because most desk accessories don’t handle weird keystrokes (some beep, others don’t do anything at all). KeyQuencer handles the keystroke as soon as it comes out of the desk accessory. I didn’t fix this unusual behaviour because doing so required some more patches, but I may take care of it in the future if someone finds it annoying.
◊  Changes made in the control panel take effect immediately under System 6.0.4 or later; those who use an older system must restart the Mac for the macros and the preferences to be updated.

• Distribution
◊  KeyQuencer can be freely distributed as long as it is not modified and there’s no charge for it. It may not be included in any commercial package without my consent. 
◊  All online services and bulletin boards may make it available to their users at no charge other than the normal connection fees.
◊  All non-profit user groups may distribute it at no charge.
◊  All magazines may publish it on floppy disk without asking me first, as long as I get a copy of the issue containing my software.
◊  All CD-ROM shareware collections and CD-ROM magazines may include it without my prior consent, as long as I get either a copy of the CD-ROM or an offer to buy the CD-ROM at a discounted price.
◊  All redistribution companies such as Educorp may distribute it, as long as I get a copy of each media containing my software and a catalog of the company’s offerings (where applicable).

• Version history
◊  1.01 - Fixed a small bug in the macro editor and added a work-around for WorldScript II. The Click extension now handles the closebox and zoombox better.
◊  1.0 - First public release (after more than 30 beta versions).

• Thanks to…
◊  Lots of help and suggestions came from Valentina Pavia, Alberto Ricci, Fabrizio Oddone, Rocco Moliterno, Massimo Lucano, Giovanni Rava, Alberto Novelli, Giorgio Berta, Peppino Ventura, Amedeo Farello, Giuseppe Carlino, Luciano Baesso, Filippo Bellotti and Masatsugu Nagata.
◊  KeyQuencer would certainly be a commercial product if I hadn’t received such a rewarding support from those who registered for my other shareware programs. I’d like to thank all my registered users one by one, but they are now way too many to list…

• Disclaimer
◊  KeyQuencer shouldn’t cause any damage, but you’re using it at your own risk. As an independent software developer, I can make no warranties whatsoever on it.

• Have fun!
◊  And don't forget to register your copy of KeyQuencer. I worked hard for many months to make it powerful and solid, yet I’m keeping the price very low so that everyone can afford it. If you’re starving, read the first paragraph again and see what else you can do to keep KeyQuencer alive.